//---------------------------------------------------------------------------------------------------------------------
// <copyright file="SensitiveDataAttribute.cs" company="blinkBox Entertainment Ltd.">
//   Copyright (c) blinkBox Entertainment Ltd. All rights reserved.
// </copyright>
// <summary>
//   Marks an item as either containing or handing sensitive data which should be obscured in trace output.
// </summary>
//---------------------------------------------------------------------------------------------------------------------

namespace BlinkBox.Diagnostics
{
    using System;

    /// <summary>
    /// Marks an item as either containing or handing sensitive data which should be obscured
    /// in trace output.
    /// </summary>
    /// <remarks>
    /// <para>
    /// This attribute may be applied to parameters or return values of methods to indicate that they
    /// contain sensitive data and should be obscured in the trace output. Alternatively entire properties,
    /// methods or constructors may be marked with this attribute and any input or output will be obscured
    /// from the trace. Note that this attribute only has an effect on the <see cref="BlinkBoxTrace.In"/> 
    /// method which takes a parameter array, and the <see cref="BlinkBoxTrace.Out{T}"/> methods that take
    /// a parameter array or return value.
    /// </para>
    /// <para>
    /// Note that in <strong>DEBUG</strong> builds when the <see cref="TraceTypes.SensitiveData"/> trace
    /// flag is used, the sensitive data can be printed out without being obscured which is useful for
    /// debugging. This flag is ignored in <strong>RELEASE</strong> builds to ensure that sensitive data
    /// cannot be traced on production systems.
    /// </para>
    /// </remarks>
    /// <example>
    /// This example shows the attributes being applied to a parameter and return value of a method and
    /// then traced using the <see cref="BlinkBoxTrace"/> class.
    /// <code>
    /// [return: SensitiveData]
    /// public string MyMethod([SensitiveData] string sensitiveVal, string publicVal)
    /// {
    ///     BlinkBoxTrace.In(sensitiveVal, publicVal)     
    ///     // ...     
    ///     return BlinkBoxTrace.Out(otherSensitiveVal);
    /// }
    /// </code>
    /// The trace output from this will be as follows when the data is obscured:
    /// <code>
    /// ... In  : MyNamespace.MyClass.MyMethod(&quot;&lt;******&gt;&quot;, &quot;publicvaluetext&quot;)
    /// ... Out : MyNamespace.MyClass.MyMethod()=&quot;&lt;******&gt;&quot;
    /// </code>
    /// </example>
    [AttributeUsage(AttributeTargets.Parameter | AttributeTargets.ReturnValue | AttributeTargets.Property | AttributeTargets.Method | AttributeTargets.Constructor)]
    public sealed class SensitiveDataAttribute : Attribute
    {
    }
}
